{smcl}
{* 1jun2011}{...}
{cmd:help medsens}{right: ({browse "http://www.stata-journal.com/article.html?article=up0036":SJ12-2: st0243_1})}
{hline}

{title:Title}

{p2colset 5 16 18 2}{...}
{p2col :{hi:medsens} {hline 2}}Estimate sensitivity analysis for causal mediation effects{p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 15 2}
{cmd:medsens}
{cmd:(}{it:model} {depvar} {varlist}{cmd:)}
{cmd:(}{it:model} {depvar} {varlist}{cmd:)}
{ifin}{cmd:,}
{opth med:iate(varname)}
{cmd:treat}{cmd:(}{it:varname}{cmd:)}
[{cmdab:sim:s}{cmd:(}{it:#}{cmd:)}
{cmd:eps(}{it:#}{cmd:)}
{cmdab:l:evel}{cmd:(}{it:#}{cmd:)}
{cmdab:gr:aph}]

{marker model}{...}
{pstd}
{it:model} in the first set of parentheses specifies the model for the mediator variable.
{it:model} in the second set of parentheses specifies the model for the outcome variable.
Available model types are OLS regression ({helpb regress}), probit
({helpb probit}), and logit ({helpb logit}).
Restrictrictions on observations specified with the {cmd:if} or
{cmd:in} qualifier apply to both models.


{title:Description}

{pstd} {cmd:medsens} is the workhorse command for conducting
sensitivity analyses for mediation effects.  The analysis proceeds by
quantifying the degree of sequential ignorability violation as the
correlation between the error terms of the mediator and outcome models,
and then calculating the true values of the average causal mediation
effect for given values of this sensitivity parameter, rho.  The
original findings are deemed sensitive if the true effects are found to
vary widely as a function of rho.  Sensitivity analysis for mediation is
highly recommended in the case of the single-experiment design where
only the treatment variable is randomized (or ignorable conditional on
covariates).  Currently, the {cmd:medsens} command handles three common
cases: 1) both the outcome and the mediator are continuous, 2) the mediator
is binary and the outcome is continuous, and 3) the mediator is
continuous and the outcome is binary.


{title:Options}

{phang}
{cmd:mediate}{cmd:(}{it:varname}{cmd:)} is required
and specifies the mediating variable to use in the analysis.

{phang} 
{cmd:treat}{cmd:(}{it:varname}{cmd:)} is required and specifies the
treatment variable to use in the analysis.

{phang}  
{cmdab:sims(}{it:#}{cmd:)} specifies the number of simulations to run.
The default is {cmd:sims(100)}.  For final production runs, the number should be
set higher (such as 500), but note that this will take longer, especially for models
with a binary mediator.

{phang} 
{cmd:eps}{cmd:(}{it:#}{cmd:)} convergence tolerance parameter for the
iterative feasible generalized least squares.  Used only when both the
mediator model and the outcome model are linear.  The default is {cmd:eps(.01)}.
Typically, users will not change this and if so will only decrease it.

{phang}
{cmd:level(}{it:#}{cmd:)} specifies the confidence level, as a
percentage, for confidence intervals.  The default is {cmd:level(95)} or
as set by {cmd:set level}.

{phang}
{cmd:graph} produces a graph of the results with the confidence
intervals.  Instead of specifying the {cmd:graph} option, you
can use the variables generated by the {cmd:medsens} command
({cmd:_med_}*) with a graph command to produce a graph of your own.


{title:Examples}

{phang}{cmd:. medsens (regress M T x) (regress Y T M x), mediate(M) treat(T) sims(1000) eps(.01)}{p_end}
{phang}{cmd:. medsens (probit M T x) (regress Y T M x), mediate(M) treat(T) sims(1000) eps(.01)}{p_end}
{phang}{cmd:. medsens (regress M T x) (probit Y T M x), mediate(M) treat(T) sims(1000) eps(.01)}{p_end}

{phang}{cmd:. twoway rarea _med_updelta0 _med_lodelta0 _med_rho, bcolor(gs14) || line _med_delta0 _med_rho , lcolor(black) ytitle("Average mediation effect") xtitle("Sensitivity parameter: p") legend(off) title("ACME(p)")} {p_end}


{title:Remarks}

{pstd} {cmd:medsens} only supports ordinary least squares and probit
because the sensitivity formula must be worked out on a case-by-case basis.
Any estimation technique other than those will produce an error.  In the
case of a binary mediator and continuous outcome, the sensitivity
analysis can take a long time, especially with larger datasets.  The
estimate of the average causal
mediation effect (ACME) as a function of rho may also be plotted with
corresponding 95% confidence intervals.  An example is given above of
plotting delta(0).

{pstd} The command also creates variables for the ACME
({cmd:_med_delta0} and {cmd:_med_delta1}) at each value of rho
({cmd:_med_rho}).  For both deltas, the low and high bounds of the 95%
confidence interval are stored in the {cmd:lo} and {cmd:up} variables.  Each time the
command is run, the existing created variables are dropped and new ones are created.


{title:Requirement}

{pstd} {cmd:medsens} requires the {cmd:moremata} package.  If not already
installed, type {cmd:ssc install moremata}.


{title:Saved results}

{pstd}{cmd:medsens} saves the following in {cmd:r()}:

{synoptset 16 tabbed}{...}
{p2col 5 16 20 2:Scalars}{p_end}
{synopt:{cmd:r(errcr)}}rho (correlation in error terms) at which ACME=0{p_end}
{synopt:{cmd:r(r2s_thresh)}}proportions of residual variance in mediator and outcome explained by hypothesized unobserved confounder{p_end}
{synopt:{cmd:r(r2t_thresh)}}proportions of total variance in mediator and outcome explained by hypothesized unobserved confounder{p_end}


{title:Bibliography and sources}

{pstd}
The procedures used for estimation are discussed extensively elsewhere.

{phang}Imai, K., L. Keele, and D. Tingley. 2010.  A general approach to
causal mediation analysis.  {it:Psychological Methods} 15: 309-334.

{phang}Imai, K., L. Keele, D. Tingley, and T. Yamamoto. 2010.  
Causal mediation analysis using R.  In
{it:Advances in Social Science Research Using R}, ed. H. D. Vinod, 129-154.
New York: Springer.{p_end}

{phang}Imai, K., L. Keele, and T. Yamamoto. 2010.  Identification,
inference, and sensitivity analysis for causal mediation effects.
{it:Statistical Sciences} 25: 51-71.

{pstd}Please cite upon use: Hicks, Raymond and Dustin Tingley (2011)
mediation: Stata package for causal mediation analysis. 

{pstd}Also cite the above journal articles that form the theoretical basis of
the package.


{title:Authors}

{pstd}Raymond Hicks{p_end}
{pstd}Niehaus Center for Globalization and Governance{p_end}
{pstd}Princeton University {p_end}
{pstd}Princeton, NJ{p_end}
{pstd}{browse "mailto:rhicks@princeton.edu":rhicks@princeton.edu}{p_end}

{pstd}Dustin Tingley {p_end}
{pstd}Department of Government{p_end}
{pstd}Harvard University{p_end}
{pstd}Cambridge, MA{p_end}
{pstd}{browse "mailto:dtingley@gov.harvard.edu":dtingley@gov.harvard.edu}{p_end}


{title:Also see}

{pstd}Further details about the analytical formulas and algorithms
used in these programs can be found at
{browse "http://imai.princeton.edu/projects/mechanisms.html":http://imai.princeton.edu/projects/mechanisms.html}.

{p 4 14 2}Article:  {it:Stata Journal}, volume 12, number 2: {browse "http://www.stata-journal.com/article.html?article=up0036":st0243_1},{break}
                    {it:Stata Journal}, volume 11, number 4: {browse "http://www.stata-journal.com/article.html?article=st0243":st0243}
{p_end}
